Amiga Tools 5

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Tools 5 / Amiga Tools 5.iso / tools / system-tools / smartcrash / smartcrash.doc < prev next >

Wrap

Text File | 1996-02-26 | 19.0 KB | 408 lines

26-Feb-1996 Documentation for ========================== ==== SmartCrash 1.1 ==== ========================== Copyright © 1995-1996 PitPlane Productions IMPORTANT! Please read copyrights, disclaimer and license parts of this document before use. *** What is SmartCrash? *** o SmartCrash is a system crash requester replacement. SmartCrash requires Kickstart 2.0 or better. *** Why SmartCrash? *** o This is the main reason: ___________________________________________ |Software Failure [_] ||¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯|| || causefailpro || || Program failed (error #80000005). || || Wait for disk activity to finish. || ||_______________________________________|| |.---------. .--------.| || Suspend | | Reboot || |`---------' `--------'| ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ FIGURE 1: Pathetic OS crash requester o Kickstart 2.0 introduced great crash requester. System didn't just guru if something went wrong, it displayed nice little requester instead. So what!? Yes, there is a "Suspend" -gadget in the requester but even so it isn't the best possible. It should be more informative. It should have more buttons to play with. Here SmartCrash comes in. o This tool is FREEWARE!! (see license) o SmartCrash is 100% assembler. o SmartCrash executable is only about 4½ K! o Uses very little extra memory! o Uses SegTracker information if available! o Support for both intuition and reqtools.library requesters. o ReqTools requester's font can be configured. o In ReqTools SmartCrash uses key shortcuts!! o Falls back to alert message if no requester can be created. o Has lots of new buttons. Just try them!! o "Skip" -button can skip failed instructions. o Displays _loads of_ information about the failure. o SmartCrash should be compatible with future kickstarts. o Enforcer hit free (obvious!) *** Notes *** o SmartCrash DOES NOT... ...replace GURUs! ...do any resource tracking! o SmartCrash has been tested on following systems: A1200 4/160 MB, 68020 @ 14MHz and A1200 10/540 MB, Blizzard 1230-III 68030 @ 50MHz o If no requester (task, in fact) can be created alert message will be shown instead. Information level of this alert is remarkably lower than real crash requester's, but you usually never see this alert message anyway. o SmartCrash is capable to skip failed instructions at least with 68020 and 68030 processors. 68040 and 68060 aren't tested and will not work completely correctly. (Sorry that's the truth, boys and girls...;-) With 68040 (and presumably 68060), in some cases, there is no way of knowing when (for example) address error occured. There are some common exceptions that work similarily in all MC680x0 family processors, though. These include at least Trap #x instructions, Chk instructions, Trapcc, Trapv etc. and they're usually called "Exceptions Instructions". Address errors, bus errors, privilege violations, illegal instructions (esp. illegal mmu instructions) can cause unstabil (even false) results on '040 and '060. o Although SmartCrash patches one execbase function and TC_TRAPCODE of many tasks it will always be possible to quit SmartCrash. The little disadvantage is that 48 bytes of memory will be lost at every quit. That isn't usually a big problem as programs like this are rarely terminated. If some other program has patched the function SmartCrash patches [that is exec.library/AddTask()] then this function is left as it is (This prevents some potential crashes!). o There is an example failure program in this distribution archive. It's called "CauseFailPro". It is the easiest (and safes) way to test SmartCrash. Just press "Skip" -button of the crash requester to proceed onwards in this avesome program :-). You can also hit "Exit" -button without memory loss. The assembler source of this faulty program is also included. (Gee!) o SmartCrash should be compatible with all future Kickstarts. Kickstart 3.0 is currently the only tested one. If SmartCrash refuses to cooperate with other kickstarts then contact the author(s). o To contact the author(s) try these: Harry Sintonen (Delta) (Gifts, cli-scripts, ASM Sources Kotipolku 30 etc. are welcome. No illegal trade.) 48710 Karhula FINLAND Marko Nippula (2nd editor of the SmartCrash. He E-Mail: mnippula@vipunen.hut.fi might not be so interested about this project nowadays though...:-) *** SmartCrash's Usage *** o SmartCrash's template is RT=USEREQTOOLS/S, RTFONTNAME, RTFONTSIZE/N RT=USEREQTOOLS/S With this switch you can suggest SmartCrash to use reqtools.library requesters instead of intuition ones. If ReqTools isn't available SmartCrash will fall back to intuition requesters. RTFONTNAME This parameter is valid when ReqTools requester is in use. You can select the font with the requester contents are shown. (For example: RTFONTNAME="xen.font") RTFONTSIZE/N Used with conjugation of RTFONTNAME. This number specifies the font's height (y-size). Default is 8 pixels. (For example: RTFONTSIZE=9) o When you execute SmartCrash it will install itself. No "Run" is needed. Second execution will remove SmartCrash. SmartCrash should always be capable to remove itself. If you have any SmartCrash requesters up and you try to remove SmartCrash, removal will wait until all the requesters are closed. o It's fairly good idea to install SmartCrash on to your system. Just copy the SmartCrash executable to C: -drawer or somewhere within your paths. Then just insert line like this... SmartCrash >NIL: USEREQTOOLS foobar.font 9 ...to your s:startup-sequence or s:user-startup. o RC (return code) is set: OK (0) SmartCrash installed ok. WARN (5) SmartCrash removed ok. ERROR (10) Things went wrong. Couldn't install! Couldn't get memory? FAIL (37) You don't have kickstart 2.0 or better. o When crashes (failures) occure a huge requester will pop up showing loads of information about the crash: ____________________________________________________________________________________ |SmartCrash 1.1 Copyright © 1995-1996 PitPlane Productions [_] ||¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯|| || Exception 5: zero divide || || Task: 1E275D20 PC: 1E26B6E2 SR: 0006 USP: 1E277A68 SSP: 1E001DB8 || || D: 000000D0 000000D1 000000D2 000000D3 000000D4 000000D5 000000D6 000000D7 || || A: 000000A0 000000A1 000000A2 000000A3 000000A4 1E26B6DE 000000A6 1E277A68 || || S: 000000A0 000000A1 1E26B6DE 1E26B6B2 000000D0 000000D1 000000D2 000000D3 || || S: 000000D4 00000001 1E271EFC 00F96C8C 00001000 1E276714 1E2784F8 000009A8 || || Command: CLI[8]: causefailpro || || || || PC=1E26B6E2 points to 'causefailpro', hunk 0000:0000006A || || A5=1E26B6DE points to 'causefailpro', hunk 0000:00000066 || || S2=1E26B6DE points to 'causefailpro', hunk 0000:00000066 || || S3=1E26B6B2 points to 'causefailpro', hunk 0000:0000003A || ||________________________________________________________________________________|| |.---------. .--------------. .------. .-------. .--------. .------.| || Suspend | | Suspend&Free | | Exit | | Debug | | Reboot | | Skip || |`---------' `--------------' `------' `-------' `--------' `------'| ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ FIGURE 2: Great SmartCrash crash requester The extractions of the requester are marked with -> - The first line will show the exception occured: -> Exception 5: zero divide - The next line will contain information about the task crashed (address of TC structure), program counter (PC, where error occured), status register (SR, CPU state), user stack pointer (USP) and supervisor stack pointer (SSP): -> Task: 1E275D20 PC: 1E26B6E2 SR: 0006 USP: 1E277A68 SSP: 1E001DB8 - Next there are four lines containg information about the processor registers and stack contents (first line: data registers, second line: address registers, last two lines: stack contents): -> D: 000000D0 000000D1 000000D2 000000D3 000000D4 000000D5 000000D6 000000D7 -> A: 000000A0 000000A1 000000A2 000000A3 000000A4 1E26B6DE 000000A6 1E277A68 -> S: 000000A0 000000A1 1E26B6DE 1E26B6B2 000000D0 000000D1 000000D2 000000D3 -> S: 000000D4 00000001 1E271EFC 00F96C8C 00001000 1E276714 1E2784F8 000009A8 - After these is line which give information about the program which caused the trouble (is it a CLI command, process or a task and the name of it): -> Command: CLI[8]: causefailpro ! Now, if you don't have SegTracker program running on the background requester's information ends here. In this case skip to documentation of buttons. - Last there are varying number of lines giving SegTracker information about some of the elements (program counter, registers, stack contents): -> PC=1E26B6E2 points to 'causefailpro', hunk 0000:0000006A -> A5=1E26B6DE points to 'causefailpro', hunk 0000:00000066 -> S2=1E26B6DE points to 'causefailpro', hunk 0000:00000066 -> S3=1E26B6B2 points to 'causefailpro', hunk 0000:0000003A - PC points to program 'causefailpro', hunk 0, offset $6A. - A5 points to program 'causefailpro', hunk 0, offset $66. - Stack at position sp+8 contains pointer to program 'causefailpro' to hunk 0, offset $66. - Stack at position sp+12 contains pointer to program 'causefailpro' to hunk 0, offset $3A. - Note that there might be references to "strange" programs as register and stack contents can be initially random. It's your task to solve whether SegTracker reference is real one or not. - Buttons: ____________________________________________________________________________________ |.---------. .--------------. .------. .-------. .--------. .------.| || Suspend | | Suspend&Free | | Exit | | Debug | | Reboot | | Skip || |`---------' `--------------' `------' `-------' `--------' `------'| ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯ FIGURE 3: All buttons in SmartCrash reguester .---------. This button works similarily to "Suspend" | Suspend | -button of system's crash requester. It `---------' just suspends the program in question. .--------------. This gadgets tries to free as much | Suspend&Free | resources as possible allocated by the `--------------' program. If crashed program is a task or a process the only effect (compared to Suspend) is that the task will be removed, not just suspended. If the process has a CLI structure (that means it was executed as a CLI command) the SegList of the program will be released and current input and output filehandles will be closed (they'll be closed only if they're different than the standard ones). This operation should be considered as "hacky". .------. This gadget causes the program in question | Exit | to quit with original stackpointer. This `------' makes sense since sometimes you could release a CLI/Shell for your use, esp. if it's the only one available!! .-------. Now this is magic! With this one you can | Debug | activate the debugger (ROMWack/SAD, you `-------' need to send DEL from your console to actually activate the debugger). The crash requester will pop up again after the debugger returns. .--------. This button does what the name says: | Reboot | reboots the machine. This button is quite `--------' useful when you feel like whanging "the three keys of doom" as your glorious program has fucked up everything again!! :-) (And hey! This can be even faster than rebooting from keyboard, at least on some A1200s) .------. Now hold you horses!! This button gives you | Skip | possibility to skip "bad" instructions!!! `------' This function works at least on 68020 and 68030 based Amigas. Now, this skip is really great esp. when you have forgotten the one "Illegal" debug instruction into your 3meg program and your program fails. You can calmly skip the illegal instruction and the program proceeds as nothing had happened. (Well you might have to hit "Skip" more than once, esp. if the illegal stuff is in some tight loop). BTW: This feature can be used when debugging programs: you can insert illegal instructions to places where you want to see the contents of registers, stack contents, state of the CPU etc. and then skip the faulty instructions with this button. Simple, ha? And remember... Enjoy the SmartCrash! *** COPYRIGHTS *** All Amiga technology is Copyright © Amiga Technologies GmbH. All rights reserved. Blizzard Turbo Boards are © 1994 phase 5 digital products. All rights reserved. SegTracker is Copyright © Michael Sinz. Reqtools.library is Copyright © Nico François. SmartCrash is Copyright © 1995-1996 PitPlane Productions. *** LICENSE *** 1. This license applies to the product called "SmartCrash", a program for the Amiga computer, published by PitPlane Productions under the concepts of FreeWare, and the accompanying documentation. The terms "Program" and "SmartCrash" below, refer to this product. The licensee is addressed as "you". 2. You may copy and distribute verbatim copies of the program's executable code and documentation as you receive it, in any medium, provided that you conspicuously and appropriately publish only the original, unmodified program, with all copyright notices and disclaimers of warranty intact and including all the accompanying documentation, example files and anything else that came with the original. 3. You may not copy and/or distribute this program without the accompanying documentation and other additional files that came with the original. You may not copy and/or distribute modified versions of this program. 4. You may not copy, modify, sublicense, distribute or transfer the program except as expressly provided under this license. Any attempt otherwise to copy, modify, sublicense, distribute or transfer the program is void, and will automatically terminate your rights to use the program under this license. However, parties who have received copies, or rights to use copies, from you under this license will not have their licenses terminated so long as such parties remain in full compliance. 5. By copying, distributing and/or using the program you indicate your acceptance of this license to do so, and all its terms and conditions. 6. Each time you redistribute the program, the recipient automatically receives a license from the original licensor to copy, distribute and/or use the program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. 7. You may not disassemble, decompile, re-source or otherwise reverse engineer the program. 8. If you wish to incorporate parts of the program into other programs, write to the author to ask for permission. 9. You agree to cease distributing the program and data involved if requested to do so by the author. 10. You may charge a fee to recover distribution costs. The fee for diskette distribution may not be more than the cost to obtain a public domain diskette from Fred Fish. *** DISCLAIMER *** NO GUARANTEE IS GIVEN NOR IMPLIED THAT THIS PROGRAM IS FIT FOR ANY USE. THIS PROGRAM AND THE INFORMATION WITHIN THIS TEXT IS PROVIDED ON "AS IS" BASIS. THE ENTIRE RISK AS TO ITS QUALITY AND PERFORMANCE IS WITH THE USER. SHOULD THE PROGRAM PROVE DEFECTIVE, THE USER (AND NOT THE AUTHOR) ASSUMES THE ENTIRE COST OF ALL NECCESSARY DAMAGES. IN NO EVENT WILL THE AUTHOR BE LIABLE FOR DIRECT, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT IN THE PROGRAM. THE AUTHOR RESERVES THE RIGHT TO MAKE CHANGES TO THE SOFTWARE OR DOCUMENTATION WITHOUT NOTICE.